/**
 * $RCSfile$
 * $Revision: $
 * $Date: $
 *
 * Copyright 2005-2007 Jive Software.
 *
 * All rights reserved. Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.jivesoftware.smackx.commands;

import org.jivesoftware.smack.XMPPException;
import org.jivesoftware.smack.packet.XMPPError;
import org.jivesoftware.smackx.Form;
import org.jivesoftware.smackx.packet.AdHocCommandData;

import java.util.List;

/**
 * An ad-hoc command is responsible for executing the provided service and
 * storing the result of the execution. Each new request will create a new
 * instance of the command, allowing information related to executions to be
 * stored in it. For example suppose that a command that retrieves the list of
 * users on a server is implemented. When the command is executed it gets that
 * list and the result is stored as a form in the command instance, i.e. the
 * <code>getForm</code> method retrieves a form with all the users.
 * <p>
 * Each command has a <tt>node</tt> that should be unique within a given JID.
 * <p>
 * Commands may have zero or more stages. Each stage is usually used for
 * gathering information required for the command execution. Users are able to
 * move forward or backward across the different stages. Commands may not be
 * cancelled while they are being executed. However, users may request the
 * "cancel" action when submitting a stage response indicating that the command
 * execution should be aborted. Thus, releasing any collected information.
 * Commands that require user interaction (i.e. have more than one stage) will
 * have to provide the data forms the user must complete in each stage and the
 * allowed actions the user might perform during each stage (e.g. go to the
 * previous stage or go to the next stage).
 * <p>
 * All the actions may throw an XMPPException if there is a problem executing
 * them. The <code>XMPPError</code> of that exception may have some specific
 * information about the problem. The possible extensions are:
 * 
 * <li><i>malformed-action</i>. Extension of a <i>bad-request</i> error.</li>
 * <li><i>bad-action</i>. Extension of a <i>bad-request</i> error.</li>
 * <li><i>bad-locale</i>. Extension of a <i>bad-request</i> error.</li>
 * <li><i>bad-payload</i>. Extension of a <i>bad-request</i> error.</li>
 * <li><i>bad-sessionid</i>. Extension of a <i>bad-request</i> error.</li>
 * <li><i>session-expired</i>. Extension of a <i>not-allowed</i> error.</li>
 * <p>
 * See the <code>SpecificErrorCondition</code> class for detailed description of
 * each one.
 * <p>
 * Use the <code>getSpecificErrorConditionFrom</code> to obtain the specific
 * information from an <code>XMPPError</code>.
 * 
 * @author Gabriel Guardincerri
 * 
 */
public abstract class AdHocCommand {
	// TODO: Analyze the redesign of command by having an ExecutionResponse as a
	// TODO: result to the execution of every action. That result should have
	// all the
	// TODO: information related to the execution, e.g. the form to fill. Maybe
	// this
	// TODO: design is more intuitive and simpler than the current one that has
	// all in
	// TODO: one class.

	private AdHocCommandData data;

	public AdHocCommand() {
		super();
		data = new AdHocCommandData();
	}

	/**
	 * Returns the specific condition of the <code>error</code> or <tt>null</tt>
	 * if the error doesn't have any.
	 * 
	 * @param error
	 *            the error the get the specific condition from.
	 * @return the specific condition of this error, or null if it doesn't have
	 *         any.
	 */
	public static SpecificErrorCondition getSpecificErrorCondition(
			XMPPError error) {
		// This method is implemented to provide an easy way of getting a packet
		// extension of the XMPPError.
		for (SpecificErrorCondition condition : SpecificErrorCondition.values()) {
			if (error.getExtension(condition.toString(),
					AdHocCommandData.SpecificError.namespace) != null) {
				return condition;
			}
		}
		return null;
	}

	/**
	 * Set the the human readable name of the command, usually used for
	 * displaying in a UI.
	 * 
	 * @param name
	 *            the name.
	 */
	public void setName(String name) {
		data.setName(name);
	}

	/**
	 * Returns the human readable name of the command.
	 * 
	 * @return the human readable name of the command
	 */
	public String getName() {
		return data.getName();
	}

	/**
	 * Sets the unique identifier of the command. This value must be unique for
	 * the <code>OwnerJID</code>.
	 * 
	 * @param node
	 *            the unique identifier of the command.
	 */
	public void setNode(String node) {
		data.setNode(node);
	}

	/**
	 * Returns the unique identifier of the command. It is unique for the
	 * <code>OwnerJID</code>.
	 * 
	 * @return the unique identifier of the command.
	 */
	public String getNode() {
		return data.getNode();
	}

	/**
	 * Returns the full JID of the owner of this command. This JID is the "to"
	 * of a execution request.
	 * 
	 * @return the owner JID.
	 */
	public abstract String getOwnerJID();

	/**
	 * Returns the notes that the command has at the current stage.
	 * 
	 * @return a list of notes.
	 */
	public List<AdHocCommandNote> getNotes() {
		return data.getNotes();
	}

	/**
	 * Adds a note to the current stage. This should be used when setting a
	 * response to the execution of an action. All the notes added here are
	 * returned by the {@link #getNotes} method during the current stage. Once
	 * the stage changes all the notes are discarded.
	 * 
	 * @param note
	 *            the note.
	 */
	protected void addNote(AdHocCommandNote note) {
		data.addNote(note);
	}

	public String getRaw() {
		return data.getChildElementXML();
	}

	/**
	 * Returns the form of the current stage. Usually it is the form that must
	 * be answered to execute the next action. If that is the case it should be
	 * used by the requester to fill all the information that the executor needs
	 * to continue to the next stage. It can also be the result of the
	 * execution.
	 * 
	 * @return the form of the current stage to fill out or the result of the
	 *         execution.
	 */
	public Form getForm() {
		if (data.getForm() == null) {
			return null;
		} else {
			return new Form(data.getForm());
		}
	}

	/**
	 * Sets the form of the current stage. This should be used when setting a
	 * response. It could be a form to fill out the information needed to go to
	 * the next stage or the result of an execution.
	 * 
	 * @param form
	 *            the form of the current stage to fill out or the result of the
	 *            execution.
	 */
	protected void setForm(Form form) {
		data.setForm(form.getDataFormToSend());
	}

	/**
	 * Executes the command. This is invoked only on the first stage of the
	 * command. It is invoked on every command. If there is a problem executing
	 * the command it throws an XMPPException.
	 * 
	 * @throws XMPPException
	 *             if there is an error executing the command.
	 */
	public abstract void execute() throws XMPPException;

	/**
	 * Executes the next action of the command with the information provided in
	 * the <code>response</code>. This form must be the answer form of the
	 * previous stage. This method will be only invoked for commands that have
	 * one or more stages. If there is a problem executing the command it throws
	 * an XMPPException.
	 * 
	 * @param response
	 *            the form answer of the previous stage.
	 * @throws XMPPException
	 *             if there is a problem executing the command.
	 */
	public abstract void next(Form response) throws XMPPException;

	/**
	 * Completes the command execution with the information provided in the
	 * <code>response</code>. This form must be the answer form of the previous
	 * stage. This method will be only invoked for commands that have one or
	 * more stages. If there is a problem executing the command it throws an
	 * XMPPException.
	 * 
	 * @param response
	 *            the form answer of the previous stage.
	 * @throws XMPPException
	 *             if there is a problem executing the command.
	 */
	public abstract void complete(Form response) throws XMPPException;

	/**
	 * Goes to the previous stage. The requester is asking to re-send the
	 * information of the previous stage. The command must change it state to
	 * the previous one. If there is a problem executing the command it throws
	 * an XMPPException.
	 * 
	 * @throws XMPPException
	 *             if there is a problem executing the command.
	 */
	public abstract void prev() throws XMPPException;

	/**
	 * Cancels the execution of the command. This can be invoked on any stage of
	 * the execution. If there is a problem executing the command it throws an
	 * XMPPException.
	 * 
	 * @throws XMPPException
	 *             if there is a problem executing the command.
	 */
	public abstract void cancel() throws XMPPException;

	/**
	 * Returns a collection with the allowed actions based on the current stage.
	 * Possible actions are: {@link Action#prev prev}, {@link Action#next next}
	 * and {@link Action#complete complete}. This method will be only invoked
	 * for commands that have one or more stages.
	 * 
	 * @return a collection with the allowed actions based on the current stage
	 *         as defined in the SessionData.
	 */
	protected List<Action> getActions() {
		return data.getActions();
	}

	/**
	 * Add an action to the current stage available actions. This should be used
	 * when creating a response.
	 * 
	 * @param action
	 *            the action.
	 */
	protected void addActionAvailable(Action action) {
		data.addAction(action);
	}

	/**
	 * Returns the action available for the current stage which is considered
	 * the equivalent to "execute". When the requester sends his reply, if no
	 * action was defined in the command then the action will be assumed
	 * "execute" thus assuming the action returned by this method. This method
	 * will never be invoked for commands that have no stages.
	 * 
	 * @return the action available for the current stage which is considered
	 *         the equivalent to "execute".
	 */
	protected Action getExecuteAction() {
		return data.getExecuteAction();
	}

	/**
	 * Sets which of the actions available for the current stage is considered
	 * the equivalent to "execute". This should be used when setting a response.
	 * When the requester sends his reply, if no action was defined in the
	 * command then the action will be assumed "execute" thus assuming the
	 * action returned by this method.
	 * 
	 * @param action
	 *            the action.
	 */
	protected void setExecuteAction(Action action) {
		data.setExecuteAction(action);
	}

	/**
	 * Returns the status of the current stage.
	 * 
	 * @return the current status.
	 */
	public Status getStatus() {
		return data.getStatus();
	}

	/**
	 * Sets the data of the current stage. This should not used.
	 * 
	 * @param data
	 *            the data.
	 */
	void setData(AdHocCommandData data) {
		this.data = data;
	}

	/**
	 * Gets the data of the current stage. This should not used.
	 * 
	 * @return the data.
	 */
	AdHocCommandData getData() {
		return data;
	}

	/**
	 * Returns true if the <code>action</code> is available in the current
	 * stage. The {@link Action#cancel cancel} action is always allowed. To
	 * define the available actions use the <code>addActionAvailable</code>
	 * method.
	 * 
	 * @param action
	 *            The action to check if it is available.
	 * @return True if the action is available for the current stage.
	 */
	protected boolean isValidAction(Action action) {
		return getActions().contains(action) || Action.cancel.equals(action);
	}

	/**
	 * The status of the stage in the adhoc command.
	 */
	public enum Status {

		/**
		 * The command is being executed.
		 */
		executing,

		/**
		 * The command has completed. The command session has ended.
		 */
		completed,

		/**
		 * The command has been canceled. The command session has ended.
		 */
		canceled
	}

	public enum Action {

		/**
		 * The command should be executed or continue to be executed. This is
		 * the default value.
		 */
		execute,

		/**
		 * The command should be canceled.
		 */
		cancel,

		/**
		 * The command should be digress to the previous stage of execution.
		 */
		prev,

		/**
		 * The command should progress to the next stage of execution.
		 */
		next,

		/**
		 * The command should be completed (if possible).
		 */
		complete,

		/**
		 * The action is unknow. This is used when a recieved message has an
		 * unknown action. It must not be used to send an execution request.
		 */
		unknown
	}

	public enum SpecificErrorCondition {

		/**
		 * The responding JID cannot accept the specified action.
		 */
		badAction("bad-action"),

		/**
		 * The responding JID does not understand the specified action.
		 */
		malformedAction("malformed-action"),

		/**
		 * The responding JID cannot accept the specified language/locale.
		 */
		badLocale("bad-locale"),

		/**
		 * The responding JID cannot accept the specified payload (e.g. the data
		 * form did not provide one or more required fields).
		 */
		badPayload("bad-payload"),

		/**
		 * The responding JID cannot accept the specified sessionid.
		 */
		badSessionid("bad-sessionid"),

		/**
		 * The requesting JID specified a sessionid that is no longer active
		 * (either because it was completed, canceled, or timed out).
		 */
		sessionExpired("session-expired");

		private String value;

		SpecificErrorCondition(String value) {
			this.value = value;
		}

		public String toString() {
			return value;
		}
	}
}